
高效的 C++ JSON 解析/生成器,提供 SAX 及 DOM 风格 API
Tencent is pleased to support the open source community by making RapidJSON available.
Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip.
Build 状态
简介
RapidJSON 是一个 C++ 的 JSON 解析器及生成器。它的灵感来自 RapidXml。
- RapidJSON 小而全。它同时支持 SAX 和 DOM 风格的 API。SAX 解析器只有约 500 行代码。
- RapidJSON 快。它的性能可与 strlen() 相比。可支持 SSE2/SSE4.2 加速。
- RapidJSON 独立。它不依赖于 BOOST 等外部库。它甚至不依赖于 STL。
- RapidJSON 对内存友好。在大部分 32/64 位机器上,每个 JSON 值只占 16 字节(除字符串外)。它预设使用一个快速的内存分配器,令分析器可以紧凑地分配内存。
- RapidJSON 对 Unicode 友好。它支持 UTF-8、UTF-16、UTF-32 (大端序/小端序),并内部支持这些编码的检测、校验及转码。例如,RapidJSON 可以在分析一个 UTF-8 文件至 DOM 时,把当中的 JSON 字符串转码至 UTF-16。它也支持代理对(surrogate pair)及 "\u0000"(空字符)。
在 这里 可读取更多特点。
JSON(JavaScript Object Notation)是一个轻量的数据交换格式。RapidJSON 应该完全遵从 RFC7159/ECMA-404,并支持可选的放宽语法。 关于 JSON 的更多信息可参考:
v1.1 中的亮点 (2016-8-25)
其他改动请参考 change log.
兼容性
RapidJSON 是跨平台的。以下是一些曾测试的平台/编译器组合:
- Visual C++ 2008/2010/2013 在 Windows (32/64-bit)
- GNU C++ 3.8.x 在 Cygwin
- Clang 3.4 在 Mac OS X (32/64-bit) 及 iOS
- Clang 3.4 在 Android NDK
用户也可以在他们的平台上生成及执行单元测试。
安装
RapidJSON 是只有头文件的 C++ 库。只需把 include/rapidjson 目录复制至系统或项目的 include 目录中。
RapidJSON 依赖于以下软件:
生成测试及例子的步骤:
- 执行 git submodule update --init 去获取 thirdparty submodules (google test)。
- 在 rapidjson 目录下,建立一个 build 目录。
- 在 build 目录下执行 cmake .. 命令以设置生成。Windows 用户可使用 cmake-gui 应用程序。
- 在 Windows 下,编译生成在 build 目录中的 solution。在 Linux 下,于 build 目录运行 make。
成功生成后,你会在 bin 的目录下找到编译后的测试及例子可执行文件。而生成的文档将位于 build 下的 doc/html 目录。要执行测试,请在 build 下执行 make test 或 ctest。使用 ctest -V 命令可获取详细的输出。
我们也可以把程序库安装至全系统中,只要在具管理权限下从 build 目录执行 make install 命令。这样会按系统的偏好设置安装所有文件。当安装 RapidJSON 后,其他的 CMake 项目需要使用它时,可以通过在 CMakeLists.txt 加入一句 find_package(RapidJSON)。
用法一览
此简单例子解析一个 JSON 字符串至一个 document (DOM),对 DOM 作出简单修改,最终把 DOM 转换(stringify)至 JSON 字符串。
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>
int main() {
const char* json = "{\"project\":\"rapidjson\",\"stars\":10}";
s.SetInt(s.GetInt() + 1);
std::cout << buffer.GetString() << std::endl;
return 0;
}
GenericDocument & Parse(const typename SourceEncoding::Ch *str)
Parse JSON text from a read-only string (with Encoding conversion)
定义 document.h:2709
bool Accept(Handler &handler) const
Generate events of this value to a Handler.
定义 document.h:1948
JSON writer
定义 writer.h:91
main RapidJSON namespace
定义 rapidjson.h:409
GenericValue< UTF8<> > Value
GenericValue with UTF8 encoding
定义 document.h:2486
GenericStringBuffer< UTF8< char >, CrtAllocator > StringBuffer
String buffer with UTF8 encoding
定义 fwd.h:61
GenericDocument< UTF8<> > Document
GenericDocument with UTF8 encoding
定义 document.h:2890
注意此例子并没有处理潜在错误。
下图展示执行过程。
simpledom
还有许多 例子 可供参考:
- DOM API
- SAX API
- Schema API
- 进阶